﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>ASP.NET Boilerplate documentation</title>
<link type="text/css" rel="stylesheet" href="bootstrap.min.css" />
</head>

<body>

<ul>
	<li><a href="#DocServerSide">Server side</a><ul>
		<li><a href="#DocGetLogger">Getting the logger</a></li>
		<li><a href="#DocControllers">Base classes with Logger</a></li>
		<li><a href="#DocConfig">Configuration</a></li>
	</ul>
	</li>
	<li><a href="#DocClient">Client side</a></li>
</ul>
<h3 id="DocServerSide">Server side</h3>
<p>ASP.NET Boilerplate uses
Castle Windsor's
<a href="http://docs.castleproject.org/Windsor.Logging-Facility.ashx" target="_blank">
logging facility</a>. It can work with different logging libraries: <strong>
Log4Net</strong>, <strong>NLog</strong>, <strong>Serilog</strong>... etc. Castle 
provides a <strong>common interface</strong> for all logger libraries. So, 
you're independent from specific logging library and can easily change it later 
if you need.</p>
<p><strong><a href="http://logging.apache.org/log4net/">Log4Net</a></strong> is one of the most popular logging libraries for 
.NET. ASP.NET Boilerplate <a href="/Templates">templates</a> come with
Log4Net properly 
configured and working. But, there is just a single-line of dependency to 
log4net (as seen in <a href="#DocConfig">configuration</a>  section), so you can 
change it to your favourite library.</p>
<h4 id="DocGetLogger">Getting the logger</h4>
<p>No matter which logging library you choice, the code to write log is same 
(thanks to Castle's common ILogger interface).</p>
<p>First, we should <strong>handle</strong> a Logger object to write logs. Since ASP.NET 
Boilerplate strongly uses <a href="/Pages/Documents/Dependency-Injection">
dependency injection</a>, we can 
easily inject a <strong>Logger</strong> object using 
<a href="/Pages/Documents/Dependency-Injection#DocPropertyInjection">property injection</a> pattern. 
See a sample class that writes a log line:</p>
<pre lang="cs"><strong>using Castle.Core.Logging</strong>; //1: Import Logging namespace

public class TaskAppService : ITaskAppService
{    
    //2: Getting a logger using property injection
    <strong>public ILogger Logger { get; set; }</strong>
    
    public TaskAppService()
    {
        //3: Do not write logs if no Logger supplied.
        <strong>Logger = NullLogger.Instance;</strong>
    }

    public void CreateTask(CreateTaskInput input)
    {
        //4: Write logs
        <strong>Logger.Info(&quot;Creating a new task with description<span lang="tr">:</span> &quot; + input.Description);</strong>

        //TODO: save task to database...
    }
}</pre>
<p><strong>First</strong>, we imported namespace of Castle's ILogger interface.</p>
<p><strong>Second</strong>, we defined a public <strong>ILogger</strong> object named 
Logger. This is the object we will write logs. Dependency injection system will set 
(inject) 
this property after creating TaskAppService object. This is known as property 
injection pattern.</p>
<p><strong>Third</strong>, we set Logger to <strong>NullLogger.Instance</strong>. 
System will work fine without this line. But this is best practice on property 
injection pattern. If no one sets the Logger, it will be <strong>null</strong> 
and we get an "object reference..." exception when we want to use it. This guaranties 
that 
it's not null. So, if no one sets the Logger, it will be NullLogger. This is 
known as null object pattern. NullLogger actually does nothing, does not write 
any logs. Thus, our class can work with and without an actual logger.</p>
<p><strong>Fourth</strong> and the last, we're writing a log text with <strong>
info</strong> level. There are 
different levels (see <a href="#DocConfig">configuration</a> section).</p>
<p>If we call the CreateTask method and check the log file, we see a log line as 
like as shown 
below:</p>

<pre>INFO  2014-07-13 13:40:23,360 [8    ] SimpleTaskSystem.Tasks.TaskAppService    - Creating a new task with description: Remember to drink milk before sleeping!</pre>

<h4 id="DocControllers">Base classes with Logger</h4>
<p>ASP.NET Boilerplate provides <strong>base classes</strong> for MVC 
controllers, Web API controllers and
<a href="/Pages/Documents/Application-Services">Application service</a> classes. 
They declare a <strong>Logger</strong> property. So, you can directly use 
this Logger to write logs, no injection needed. Example:</p>
<pre lang="cs">public class HomeController : SimpleTaskSystemControllerBase
{
    public ActionResult Index()
    { 
        <strong>Logger.Debug(&quot;A sample log message...&quot;);</strong>
        return View();
    }
}</pre>
<p>Note that SimpleTaskSystemControllerBase is our application specific base 
controller that inherits <strong>AbpController.</strong> Thus, it can directly use Logger. Logger also exists in <strong>AbpApiController</strong> 
base class 
for Web API Controllers and
<a href="/Pages/Documents/Application-Services#DocAppServiceClass"><strong>
ApplicationService</strong></a> class for application services.. You can also write your own common base class for other 
classes. Then, you will not have to inject logger every time.</p>

<h4 id="DocConfig">Configuration</h4>

<p>All configuration is done for Log4Net when you create your application from ASP.NET 
Boilerplate <a href="/Templates">templates</a>.</p>
<p>Default configuration's log format is as show below (for each line):</p>
<ul>
	<li><strong>Log level</strong>: DEBUG, INFO, WARN, ERROR or FATAL.</li>
	<li><strong>Date and time</strong>: The time when the log line is written.</li>
	<li><strong>Thread number</strong>: The thread number that writes the log 
	line.</li>
	<li><strong>Logger name</strong>: This is generally the class name which 
	writes the log line.</li>
	<li><strong>Log text</strong>: Actual log text that you write.</li>
</ul>
<p>It's defined in the <strong>log4net.config</strong> file of the application 
as shown below:</p>
<pre lang="xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot; ?&gt;
&lt;log4net&gt;
  &lt;appender name=&quot;RollingFileAppender&quot; type=&quot;log4net.Appender.RollingFileAppender&quot; &gt;
    &lt;file value=&quot;Logs/Logs.txt&quot; /&gt;
    &lt;appendToFile value=&quot;true&quot; /&gt;
    &lt;rollingStyle value=&quot;Size&quot; /&gt;
    &lt;maxSizeRollBackups value=&quot;10&quot; /&gt;
    &lt;maximumFileSize value=&quot;10000KB&quot; /&gt;
    &lt;staticLogFileName value=&quot;true&quot; /&gt;
    &lt;layout type=&quot;log4net.Layout.PatternLayout&quot;&gt;
        &lt;conversionPattern value=&quot;<strong>%-5level %date [%-5.5thread] %-40.40logger - %message%newline</strong>&quot; /&gt;
    &lt;/layout&gt;
  &lt;/appender&gt;
  &lt;root&gt;
    &lt;appender-ref ref=&quot;RollingFileAppender&quot; /&gt;
    &lt;level value=&quot;DEBUG&quot; /&gt;
  &lt;/root&gt;
  &lt;logger name=&quot;NHibernate&quot;&gt;
    &lt;level value=&quot;WARN&quot; /&gt;
  &lt;/logger&gt;
&lt;/log4net&gt;</pre>
<p>Log4Net is highly configurable and strong logging library. You can write logs 
in different formats and to different targets (text file, database...). You can 
set minimum log levels (as set for NHibernate in this configuration). You can 
write diffent loggers to different log files. It can automatically backup and 
create new log file when it reaches to a specific size (Rolling file adapter 
with 10000 KB per file in this configuration) and so on... Read it's own 
confuguration
<a href="http://logging.apache.org/log4net/release/config-examples.html" target="_blank">
documentation</a> for more.</p>

<p>Finally, in the Global.asax file, we declare that we use Log4Net with 
log4net.config file:</p>
<pre lang="cs">public class MvcApplication : AbpWebApplication
{
    protected override void Application_Start(object sender, EventArgs e)
    {
        <strong>IocManager.Instance.IocContainer.AddFacility&lt;LoggingFacility&gt;(f =&gt; f.UseLog4Net().WithConfig(&quot;log4net.config&quot;));</strong>
        base.Application_Start(sender, e);
    }
}</pre>
<p>This is <strong>the only code line we directly depend on log4net</strong>. 
Also, only the web project depends on log4net library's
<a href="https://www.nuget.org/packages/log4net/" target="_blank">nuget package</a>. 
So, you can easily change to another library without changing your logging code.</p>

<h3 id="DocClient">Client side</h3>
<p>ASP.NET Boilerplate defines a javascript logging API for client side. It logs 
to browser's console as default. Sample javascript code to write logs:</p>
<pre lang="js">abp.log.warn('a sample log message...');</pre>
<p>For more information, see <a href="/Pages/Documents/Javascript-API/Logging">
logging API documentation</a>.</p>

</body>

</html>
